/*
 * Copyright (c) 2011 Obix Labs Limited
 * Redistribution and use in source and binary forms, 
 * with or without modification, are permitted provided 
 * that the following conditions are met:
 * 
 * 		Redistribution of source code must retain the above 
 * 		copyright notice, this list of conditions and the 
 * 		following disclaimer.
 *
 * 		Redistribution in binary form must reproduce the 
 * 		above copyright notice, this list of conditions 
 * 		and the following disclaimer in the documentation 
 * 		and/or other materials provided with the distribution.
 * 
 * 	THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT A WARRANTY OF 
 * 	ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS 
 * 	AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 
 * 	FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, 
 * 	ARE HEREBY EXCLUDED. OBIX LABS LIMITED ("Obix Labs") AND ITS 
 * 	LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE 
 * 	AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR 
 * 	ITS DERIVATIVES. IN NO EVENT WILL Obix Labs OR ITS LICENSORS BE 
 * 	LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, 
 * 	INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
 * 	DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 
 * 	LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS 
 * 	SOFTWARE, EVEN IF Obix Labs HAS BEEN ADVISED OF THE POSSIBILITY OF 
 * 	SUCH DAMAGES.
 */
package com.obixlabs.commons.security;

import java.util.List;

import com.obixlabs.commons.ObixException;

/**
 * <p>
 * Generates a password based on one or more {@link PasswordRequirement rules/requirements}.
 * </p>
 * 
 * @see PasswordGeneratorDefaultImpl
 * @see PasswordRequirement
 * @see PasswordBuffer
 */
public interface PasswordGenerator
{
        /**
         * <p>
         * Generates a password conforming to the given {@link List list} of {@link PasswordRequirement requirements}.
         * </p>
         * 
         * @param requirements  The {@link PasswordRequirement rules} according to which the password 
         * is generated. 
         * @return      A password which corresponds to/satisfies the specified  {@link PasswordRequirement rules}.
         * 
         * @throws ObixException        If a password could not be generated according to the given rules. This would 
         * most likely be due to unsatisfiable (or conflicting) requirements. 
         */
	String generatePassword(List<PasswordRequirement> requirements) throws ObixException;
	
	/**
	 * <p>
	 * Generates a password which conforms to a given {@link List list} of {@link PasswordRequirement requirements}, 
	 * and is of a length that falls below or is equal to a pre-specified maximum.
	 * </p>
	 * 
         * @param requirements  The {@link PasswordRequirement rules} according to which the password 
         * is generated. 
         *  
	 * @param maximumLength        The maximum permissible length of the returned password.
	 * 
         * @return      A password which corresponds to/satisfies the specified  {@link PasswordRequirement rules},
         * and which is not longer than the specified maximum length.
         * 
         * @throws ObixException        If a password could not be generated according to the given rules. This would 
         * most likely be due to unsatisfiable (or conflicting) requirements (including the maximum length). A good 
         * example of how this could occur is if the maximum size is specified as 0, and the a non-empty {@link List list} 
         * of  {@link PasswordRequirement rules} is specified.
	 */
	String generatePassword(List<PasswordRequirement> requirements, int maximumLength) throws ObixException;	
}